home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kdialogbase.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  55.9 KB  |  1,633 lines
  1. /*
  2.  *  This file is part of the KDE Libraries
  3.  *  Copyright (C) 1999-2001 Mirko Boehm (mirko@kde.org) and
  4.  *  Espen Sand (espen@kde.org)
  5.  *  Holger Freyther <freyther@kde.org>
  6.  *
  7.  *  This library is free software; you can redistribute it and/or
  8.  *  modify it under the terms of the GNU Library General Public
  9.  *  License as published by the Free Software Foundation; either
  10.  *  version 2 of the License, or (at your option) any later version.
  11.  *
  12.  *  This library is distributed in the hope that it will be useful,
  13.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15.  *  Library General Public License for more details.
  16.  *
  17.  *  You should have received a copy of the GNU Library General Public License
  18.  *  along with this library; see the file COPYING.LIB.  If not, write to
  19.  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  20.  *  Boston, MA 02110-1301, USA.
  21.  *
  22.  */
  23. #ifndef _KDIALOG_BASE_H_
  24. #define _KDIALOG_BASE_H_
  25.  
  26. #include <kdialog.h>
  27. #include <kjanuswidget.h>
  28. #include <kguiitem.h>
  29. #include <kstdguiitem.h>
  30. #include <qptrlist.h>
  31.  
  32. class QPushButton;
  33. class KSeparator;
  34. class KURLLabel;
  35. class QBoxLayout;
  36. class QPixmap;
  37. class KGuiItem;
  38. /**
  39.  * Used internally by KDialogBase.
  40.  * @internal
  41.  */
  42. class KDialogBaseButton;
  43.  
  44. /**
  45.  * Used internally by KDialogBase.
  46.  * @internal
  47.  */
  48. class KDialogBaseTile;
  49.  
  50. /**
  51.  * @short A dialog base class with standard buttons and predefined layouts.
  52.  *
  53.  * Provides basic functionality needed by nearly all dialogs.
  54.  *
  55.  * It offers the standard action buttons you'd expect to find in a
  56.  * dialog as well as the capability to define at most three configurable
  57.  * buttons. You can define a main widget that contains your specific
  58.  * dialog layout or you can use a predefined layout. Currently, @p
  59.  * TreeList/Paged, @p Tabbed, @p Plain, @p Swallow and @p IconList
  60.  * mode layouts (faces) are available.
  61.  *
  62.  * The class takes care of the geometry management. You only need to define
  63.  * a minimum size for the widget you want to use as the main widget.
  64.  *
  65.  * You can set a background tile (pixmap) for parts of the dialog. The
  66.  * tile you select is shared by all instances of this class in your
  67.  * application so that they all get the same look and feel.
  68.  *
  69.  * There is a tutorial available on http://developer.kde.org/ (NOT YET)
  70.  * that contains
  71.  * copy/paste examples as well a screenshots on how to use this class.
  72.  *
  73.  * <b>Standard buttons (action buttons):</b>\n
  74.  *
  75.  * You select which buttons should be displayed, but you do not choose the
  76.  * order in which they are displayed. This ensures a standard interface in
  77.  * KDE. The button order can be changed, but this ability is only available
  78.  * for a central KDE control tool. The following buttons are available:
  79.  * OK, Cancel/Close, Apply/Try, Default, Help and three user definable
  80.  * buttons: User1, User2 and User3. You must specify the text of the UserN
  81.  * buttons. Each button has a virtual slot so you can overload the method
  82.  * when required. The default slots emit a signal as well, so you can choose
  83.  * to connect a signal instead of overriding the slot.
  84.  * The default implementation of slotHelp() will automatically enable
  85.  * the help system if you have provided a path to the help text.
  86.  * slotCancel() and slotClose() will run QDialog::reject()
  87.  * while slotOk() will run QDialog::accept(). You define a default
  88.  * button in the constructor.
  89.  *
  90.  * If you don't want any buttons at all because your dialog is special
  91.  * in some way, then set the buttonMask argument in the constructor to zero
  92.  * (0). The optional button box separator line should not be enabled
  93.  * in this case. Note that the KDialogBase will animate a button press
  94.  * when the user press Escape. The button that is enabled is either Cancel,
  95.  * Close or the button that is defined by setEscapeButton() The
  96.  * animation will not take place when the buttonMask is zero. Your
  97.  * custom dialog code should reimplement the keyPressEvent and
  98.  * animate the cancel button so that the dialog behaves like regular
  99.  * dialogs. NOTE: None of the regular slots (like slotOk() ) or
  100.  * signals that are related to the standard action buttons will be used
  101.  * when you don't use these buttons.
  102.  *
  103.  * <b>Dialog shapes:</b>\n
  104.  *
  105.  * You can either use one of the prebuilt, easy to use, faces or
  106.  * define your own main widget. The dialog provides ready to use
  107.  * TreeList, Tabbed, Plain, Swallow and IconList faces. KDialogBase uses
  108.  * the KJanusWidget class internally to accomplish this. If you
  109.  * use TreeList, Tabbed or IconList mode, then add pages with addPage().
  110.  *
  111.  * Pages that have been added can be removed again by simply deleting
  112.  * the page.
  113.  *
  114.  * If you want complete control of how the dialog contents should look,
  115.  * then you can define a main widget by using setMainWidget(). You
  116.  * only need to set the minimum size of that widget and the dialog will
  117.  * resize itself to fit this minimum size.  The dialog is resizeable, but
  118.  * cannot be made smaller than its minimum size.
  119.  *
  120.  * <b>Layout:</b>\n
  121.  *
  122.  * The dialog consists of a help area on top (becomes visible if you define
  123.  * a help path and use enableLinkedHelp()), the main area which is
  124.  * the built-in dialog face or your own widget in the middle and by default
  125.  * a button box at the bottom. The button box can also be placed at the
  126.  * right edge (to the right of the main widget). Use
  127.  * setButtonBoxOrientation() to control this behavior. A separator
  128.  * can be placed above the button box (or to the left when the button box
  129.  * is at the right edge). Normally you specify that you want a separator
  130.  * in the constructor, but you can use enableButtonSeparator() as well.
  131.  *
  132.  * <b>Standard compliance:</b>\n
  133.  *
  134.  * The class is derived from KDialog, so you get automatic access to
  135.  * the KDialog::marginHint(), KDialog::spacingHint() and the
  136.  * extended KDialog::setCaption() method. NOTE: The main widget you
  137.  * use will be positioned inside the dialog using a margin (or border)
  138.  * equal to KDialog::marginHint(). You should not add a margin yourself,
  139.  * since one will be added automatically.
  140.  * The example below (from kedit) shows how you use the top level widget
  141.  * and its layout. The second argument (the border) to QVBoxLayout
  142.  * is 0. This situation is valid for addPage , addVBoxPage ,
  143.  * addHBoxPage , addGridPage , makeMainWidget ,
  144.  * makeVBoxMainWidget , makeHBoxMainWidget and
  145.  * makeGridMainWidget as well.
  146.  *
  147.  * Example:
  148.  *
  149.  * \code
  150.  * UrlDlg::UrlDlg( QWidget *parent, const QString& caption,
  151.  *                 const QString& urltext)
  152.  *   : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true )
  153.  * {
  154.  *   QWidget *page = new QWidget( this );
  155.  *   setMainWidget(page);
  156.  *   QVBoxLayout *topLayout = new QVBoxLayout( page, 0, spacingHint() );
  157.  *
  158.  *   QLabel *label = new QLabel( caption, page, "caption" );
  159.  *   topLayout->addWidget( label );
  160.  *
  161.  *   lineedit = new QLineEdit( urltext, page, "lineedit" );
  162.  *   lineedit->setMinimumWidth(fontMetrics().maxWidth()*20);
  163.  *   topLayout->addWidget( lineedit );
  164.  *
  165.  *   topLayout->addStretch(10);
  166.  * }
  167.  * \endcode
  168.  *
  169.  * If you use makeVBoxMainWidget(), then the dialog above can be made
  170.  * simpler but you lose the ability to add a stretchable area:
  171.  *
  172.  * \code
  173.  * UrlDlg::UrlDlg( QWidget *parent, const QString& caption,
  174.  *                 const QString& urltext)
  175.  * : KDialogBase( parent, "urldialog", true, caption, Ok|Cancel, Ok, true )
  176.  * {
  177.  *   QVBox *page = makeVBoxMainWidget();
  178.  *   QLabel *label = new QLabel( caption, page, "caption" );
  179.  *
  180.  *   lineedit = new QLineEdit( urltext, page, "lineedit" );
  181.  *   lineedit->setMinimumWidth(fontMetrics().maxWidth()*20);
  182.  * }
  183.  * \endcode
  184.  *
  185.  * This class can be used in many ways. Note that most KDE ui widgets
  186.  * and many of KDE core applications use the KDialogBase so for more
  187.  * inspiration you should study the code for these.
  188.  *
  189.  * @author Mirko Boehm (mirko@kde.org) and Espen Sand (espen@kde.org)
  190.  */
  191. class KDEUI_EXPORT KDialogBase : public KDialog
  192. {
  193.   Q_OBJECT
  194.  
  195.   public:
  196.  
  197.     enum ButtonCode
  198.     {
  199.       Help    = 0x00000001, ///< Show Help button. 
  200.       Default = 0x00000002, ///< Show Default button.
  201.       Ok      = 0x00000004, ///< Show Ok button.
  202.       Apply   = 0x00000008, ///< Show Apply button.
  203.       Try     = 0x00000010, ///< Show Try button.
  204.       Cancel  = 0x00000020, ///< Show Cancel-button.
  205.       Close   = 0x00000040, ///< Show Close-button.
  206.       User1   = 0x00000080, ///< Show User defined button 1.
  207.       User2   = 0x00000100, ///< Show User defined button 2.
  208.       User3   = 0x00000200, ///< Show User defined button 3.
  209.       No      = 0x00000080, ///< Show No button.
  210.       Yes     = 0x00000100, ///< Show Yes button.
  211.       Details = 0x00000400, ///< Show Details button.
  212.       Filler  = 0x40000000, ///< @internal Ignored when used in a constructor.
  213.       Stretch = 0x80000000, ///< @internal Ignored when used in a constructor.
  214.       NoDefault             ///< Used when specifying a default button; indicates that no button should be marked by default. @since 3.3
  215.     };
  216.  
  217.     enum ActionButtonStyle
  218.     {
  219.       ActionStyle0=0, // KDE std
  220.       ActionStyle1,
  221.       ActionStyle2,
  222.       ActionStyle3,
  223.       ActionStyle4,
  224.       ActionStyleMAX
  225.     };
  226.  
  227.     /**
  228.      *  @li @p TreeList - A dialog with a tree on the left side and a
  229.      *                    representation of the contents on the right side.
  230.      *  @li @p Tabbed -   A dialog using a QTabWidget.
  231.      *  @li @p Plain -    A normal dialog. Use plainPage() as parent for widgets.
  232.      *  @li @p Swallow -  Simplifes the usage of existing widgets. You specify
  233.      *                    the widget to be displayed by setMainWidget().
  234.      *  @li @p IconList - A dialog with an iconlist on the left side and a
  235.      *                    representation of the contents on the right side.
  236.      */
  237.     enum DialogType
  238.     {
  239.       TreeList  = KJanusWidget::TreeList,
  240.       Tabbed    = KJanusWidget::Tabbed,
  241.       Plain     = KJanusWidget::Plain,
  242.       Swallow   = KJanusWidget::Swallow,
  243.       IconList  = KJanusWidget::IconList
  244.     };
  245.  
  246.   public:
  247.  
  248.     /**
  249.      * Constructor for the standard mode where you must specify the main
  250.      * widget with setMainWidget() .
  251.      *
  252.      * @param parent Parent of the dialog.
  253.      * @param name Dialog name (for internal use only)
  254.      * @param modal Controls dialog modality. If @p false, the rest of the
  255.      *        program interface (example: other dialogs) is accessible while
  256.      *        the dialog is open.
  257.      * @param caption The dialog caption. Do not specify the application name
  258.      *        here. The class will take care of that.
  259.      * @param buttonMask Specifies which buttons will be visible. If zero
  260.      *        (0) no button box will be made.
  261.      * @param defaultButton Specifies which button will be marked as
  262.      *        the default. Use ButtonCode::NoDefault to indicate that no button
  263.      *        should be marked as the default button.
  264.      * @param separator If @p true, a separator line is drawn between the
  265.      *        action buttons and the main widget.
  266.      * @param user1 User button1 item.
  267.      * @param user2 User button2 item.
  268.      * @param user3 User button3 item.
  269.      */
  270.     KDialogBase( QWidget *parent=0, const char *name=0, bool modal=true,
  271.          const QString &caption=QString::null,
  272.          int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok,
  273.          bool separator=false,
  274.          const KGuiItem &user1=KGuiItem(),
  275.          const KGuiItem &user2=KGuiItem(),
  276.          const KGuiItem &user3=KGuiItem() );
  277.  
  278.     /**
  279.      * In KDE4 a WFlag paramater should be added after modal and next
  280.      * function can be removed.
  281.      *
  282.      * Constructor for the predefined layout mode where you specify the
  283.      * kind of layout (face).
  284.      *
  285.      * @param dialogFace You can use TreeList, Tabbed, Plain, Swallow or
  286.      *        IconList.
  287.      * @param caption The dialog caption. Do not specify the application name
  288.      *        here. The class will take care of that.
  289.      * @param buttonMask Specifies which buttons will be visible. If zero
  290.      *        (0) no button box will be made.
  291.      * @param defaultButton Specifies which button will be marked as
  292.      *        the default. Use ButtonCode::NoDefault to indicate that no button
  293.      *        should be marked as the default button.
  294.      * @param parent Parent of the dialog.
  295.      * @param name Dialog name (for internal use only).
  296.      * @param modal Controls dialog modality. If @p false, the rest of the
  297.      *        program interface (example: other dialogs) is accessible while
  298.      *        the dialog is open.
  299.      * @param separator If @p true, a separator line is drawn between the
  300.      *        action buttons and the main widget.
  301.      * @param user1 User button1 text item.
  302.      * @param user2 User button2 text item.
  303.      * @param user3 User button3 text item.
  304.      */
  305.     KDialogBase( int dialogFace, const QString &caption,
  306.          int buttonMask, ButtonCode defaultButton,
  307.          QWidget *parent=0, const char *name=0, bool modal=true,
  308.          bool separator=false,
  309.          const KGuiItem &user1=KGuiItem(),
  310.          const KGuiItem &user2=KGuiItem(),
  311.          const KGuiItem &user3=KGuiItem() );
  312.  
  313.  
  314.     /**
  315.      * Constructor for the predefined layout mode where you specify the
  316.      * kind of layout (face).
  317.      *
  318.      * @param dialogFace You can use TreeList, Tabbed, Plain, Swallow or
  319.      *        IconList.
  320.      * @param f widget flags, by default it is just set to WStyle_DialogBorder.
  321.      * @param caption The dialog caption. Do not specify the application name
  322.      *        here. The class will take care of that.
  323.      * @param parent Parent of the dialog.
  324.      * @param name Dialog name (for internal use only).
  325.      * @param modal Controls dialog modality. If @p false, the rest of the
  326.      *        program interface (example: other dialogs) is accessible while
  327.      *        the dialog is open.
  328.      * @param buttonMask Specifies which buttons will be visible. If zero
  329.      *        (0) no button box will be made.
  330.      * @param defaultButton Specifies which button will be marked as
  331.      *        the default. Use ButtonCode::NoDefault to indicate that no button
  332.      *        should be marked as the default button.
  333.      * @param separator If @p true, a separator line is drawn between the
  334.      *        action buttons and the main widget.
  335.      * @param user1 User button1 text item.
  336.      * @param user2 User button2 text item.
  337.      * @param user3 User button3 text item.
  338.      * @since: 3.2
  339.      */
  340.  
  341.     KDialogBase( KDialogBase::DialogType dialogFace, WFlags f,
  342.          QWidget *parent=0, const char *name=0, bool modal=true,
  343.          const QString &caption=QString::null,
  344.          int buttonMask=Ok|Apply|Cancel, ButtonCode defaultButton=Ok,
  345.          bool separator=false,
  346.          const KGuiItem &user1=KGuiItem(),
  347.          const KGuiItem &user2=KGuiItem(),
  348.          const KGuiItem &user3=KGuiItem() );
  349.  
  350.     /**
  351.      * Constructor for a message box mode where the @p buttonMask can only
  352.      * contain Yes, No, or Cancel.
  353.      *
  354.      * If you need other names you can rename
  355.      * the buttons with setButtonText(). The dialog box is not resizable
  356.      * by default but this can be changed by setInitialSize(). If you
  357.      * select 'modal' to be true, the dialog will return Yes, No, or Cancel
  358.      * when closed otherwise you can use the signals yesClicked(),
  359.      * noClicked(), or cancelClicked() to determine the state.
  360.      *
  361.      * @param caption The dialog caption. Do not specify the application name
  362.      *        here. The class will take care of that.
  363.      * @param buttonMask Specifies which buttons will be visible. If zero
  364.      *        (0) no button box will be made.
  365.      * @param defaultButton Specifies which button will be marked as
  366.      *        the default. Use ButtonCode::NoDefault to indicate that no button
  367.      *        should be marked as the default button.
  368.      * @param escapeButton Specifies which button will be activated by
  369.      *        when the dialog receives a @p Key_Escape keypress.
  370.      * @param parent Parent of the dialog.
  371.      * @param name Dialog name (for internal use only).
  372.      * @param modal Controls dialog modality. If @p false, the rest of the
  373.      *        program interface (example: other dialogs) is accessible
  374.      *        while the dialog is open.
  375.      * @param separator If @p true, a separator line is drawn between the
  376.      *        action buttons and the main widget.
  377.      * @param yes Text to use for the first button (defaults to i18n("Yes"))
  378.      * @param no Text to use for the second button (defaults to i18n("No"))
  379.      * @param cancel Text to use for the third button (defaults to i18n("Cancel"))
  380.      */
  381.     KDialogBase( const QString &caption, int buttonMask=Yes|No|Cancel,
  382.          ButtonCode defaultButton=Yes, ButtonCode escapeButton=Cancel,
  383.          QWidget *parent=0, const char *name=0,
  384.          bool modal=true, bool separator=false,
  385.          const KGuiItem &yes = KStdGuiItem::yes(), // i18n("&Yes")
  386.          const KGuiItem &no = KStdGuiItem::no(), // i18n("&No"),
  387.          const KGuiItem &cancel = KStdGuiItem::cancel() // i18n("&Cancel")
  388.          );
  389.  
  390.     /**
  391.      * Destructor.
  392.      */
  393.     ~KDialogBase();
  394.  
  395.     /**
  396.      * Sets the orientation of the button box.
  397.      *
  398.      * It can be @p Vertical or @p Horizontal. If @p Horizontal
  399.      * (default), the button box is positioned at the bottom of the
  400.      * dialog. If @p Vertical it will be placed at the right edge of the
  401.      * dialog.
  402.      *
  403.      * @param orientation The button box orientation.
  404.      */
  405.     void setButtonBoxOrientation( int orientation );
  406.  
  407.     /**
  408.      * Sets the button that will be activated when the Escape key
  409.      * is pressed.
  410.      *
  411.      * Normally you should not use this function. By default,
  412.      * the Escape key is mapped to either the Cancel or the Close button
  413.      * if one of these buttons are defined. The user expects that Escape will
  414.      * cancel an operation so use this function with caution.
  415.      *
  416.      * @param id The button code.
  417.      */
  418.     void setEscapeButton( ButtonCode id );
  419.  
  420.  
  421.     /**
  422.      * Adjust the size of the dialog to fit the contents just before
  423.      * QDialog::exec() or QDialog::show() is called.
  424.      *
  425.      * This method will not be called if the dialog has been explicitly
  426.      * resized before showing it.
  427.      **/
  428.     virtual void adjustSize();
  429.     virtual QSize sizeHint() const;
  430.     virtual QSize minimumSizeHint() const;
  431.  
  432.     /**
  433.      * Retrieve the empty page when the predefined layout is used in @p Plain
  434.      * mode.
  435.      *
  436.      * This widget must be used as the toplevel widget of your dialog
  437.      * code.
  438.      *
  439.      * @return The widget or 0 if the predefined layout mode is not @p Plain
  440.      *         or if you don't use any predefined layout.
  441.      */
  442.     QFrame *plainPage();
  443.  
  444.     /**
  445.      * Add a page to the dialog when the class is used in @p TreeList ,
  446.      * @p IconList or @p Tabbed mode.
  447.      *
  448.      * The returned widget must be used as the
  449.      * toplevel widget for this particular page.
  450.      * Note: The returned frame widget has no
  451.      * layout manager associated with it. In order to use it you must
  452.      * create a layout yourself as the example below illustrates:
  453.      *
  454.      * \code
  455.      * QFrame *page = addPage( i18n("Layout") );
  456.      * QVBoxLayout *topLayout = new QVBoxLayout( page, 0, KDialog::spacingHint() );
  457.      * QLabel *label = new QLabel( i18n("Layout type"), page );
  458.      * topLayout->addWidget( label );
  459.      * ..
  460.      * \endcode
  461.      *
  462.      * @param itemName String used in the list or as tab item name.
  463.      * @param header Header text use in the list modes. Ignored in @p Tabbed
  464.      *        mode. If empty, the item text is used instead.
  465.      * @param pixmap Used in @p IconList mode. You should prefer a pixmap
  466.      *        with size 32x32 pixels.
  467.      *
  468.      * @return The page widget which must be used as the toplevel widget for
  469.      *         the page.
  470.      */
  471.     QFrame  *addPage( const QString &itemName,
  472.               const QString &header=QString::null,
  473.               const QPixmap &pixmap=QPixmap() );
  474.  
  475.     /**
  476.      * This is like addPage() just above, with the difference that the first
  477.      * element is a list of strings.
  478.      *
  479.      * These strings are used to form a path
  480.      * of folders down to the given page. The initial elements are names
  481.      * for the folders, while the last element is the name of the page.
  482.      * Note: This does yet only work for the @p TreeList face. Later this may
  483.      * be added for the @p IconList face too. In other faces than the
  484.      * @p TreeList, all the strings except the last one is ignored.
  485.      **/
  486.     QFrame  *addPage( const QStringList &items,
  487.               const QString &header=QString::null,
  488.               const QPixmap &pixmap=QPixmap() );
  489.  
  490.     /**
  491.      * Add a page to the dialog when the class is used in @p TreeList,
  492.      * @p IconList or @p Tabbed mode.
  493.      *
  494.      * The returned widget must be used as the toplevel widget for
  495.      * this particular page. The widget contains a QVBoxLayout
  496.      * layout so the widget children are lined up vertically.  You can
  497.      * use it as follows:
  498.      *
  499.      * \code
  500.      * QVBox *page = addVBoxPage( i18n("Layout") );
  501.      * QLabel *label = new QLabel( i18n("Layout type"), page );
  502.      * ..
  503.      * \endcode
  504.      *
  505.      * @param itemName String used in the list or as tab item name.
  506.      * @param header Header text use in the list modes. Ignored in @p Tabbed
  507.      *        mode. If empty, the item text is used instead.
  508.      * @param pixmap Used in @p IconList mode. You should prefer a pixmap
  509.      *        with size 32x32 pixels.
  510.      *
  511.      * @return The page widget which must be used as the toplevel widget for
  512.      *         the page.
  513.      */
  514.     QVBox *addVBoxPage( const QString &itemName,
  515.             const QString &header=QString::null,
  516.             const QPixmap &pixmap=QPixmap() );
  517.  
  518.     /**
  519.      * This is like addVBoxPage() just above, with the difference
  520.      * that the first element is a list of strings.
  521.      *
  522.      * These strings are used to form a path
  523.      * of folders down to the given page. The initial elements are names
  524.      * for the folders, while the last element is the name of the page.
  525.      * Note: This does yet only work for the @p TreeList face. Later this may
  526.      * be added for the @p IconList face too. In other faces than the
  527.      * @p TreeList, all the strings except the last one is ignored.
  528.      **/
  529.     QVBox *addVBoxPage( const QStringList &items,
  530.             const QString &header=QString::null,
  531.             const QPixmap &pixmap=QPixmap() );
  532.  
  533.     /**
  534.      * Add a page to the dialog when the class is used in @p TreeList,
  535.      * @p IconList or @p Tabbed mode.
  536.      *
  537.      * The returned widget must be used as the
  538.      * toplevel widget for this particular page. The widget contains a
  539.      * QHBoxLayout layout so the widget children are lined up horizontally.
  540.      * You can use it as follows:
  541.      *
  542.      * @param itemName String used in the list or as tab item name.
  543.      * @param header Header text use in the list modes. Ignored in Tabbed
  544.      *        mode. If empty, the item text is used instead.
  545.      * @param pixmap Used in IconList mode. You should prefer a pixmap
  546.      *        with size 32x32 pixels.
  547.      *
  548.      * @return The page widget which must be used as the toplevel widget for
  549.      *         the page.
  550.      */
  551.     QHBox *addHBoxPage( const QString &itemName,
  552.             const QString &header=QString::null,
  553.             const QPixmap &pixmap=QPixmap() );
  554.  
  555.     /**
  556.      * This is like addHBoxPage() just above, with the
  557.      * difference that the first element is a list of strings.
  558.      *
  559.      * These strings are used to form a path
  560.      * of folders down to the given page. The initial elements are names
  561.      * for the folders, while the last element is the name of the page.
  562.      * Note: This does yet only work for the @p TreeList face. Later this may
  563.      * be added for the @p IconList face too. In other faces than the
  564.      * @p TreeList, all the strings except the last one is ignored.
  565.      **/
  566.     QHBox *addHBoxPage( const QStringList &items,
  567.             const QString &header=QString::null,
  568.             const QPixmap &pixmap=QPixmap() );
  569.  
  570.     /**
  571.      * Add a page to the dialog when the class is used in @p TreeList,
  572.      * @p IconList or @p Tabbed mode.
  573.      *
  574.      * The returned widget must be used as the
  575.      * toplevel widget for this particular page. The widget contains a
  576.      * QGridLayout layout so the widget children are  positioned in a grid.
  577.      *
  578.      * @param n Specifies the number of columns if @p dir is Qt::Horizontal
  579.      *          or the number of rows if @p dir is Qt::Vertical.
  580.      * @param dir Can be Qt::Horizontal or Qt::Vertical.
  581.      * @param itemName String used in the list or as tab item name.
  582.      * @param header Header text use in the list modes @p Ignored in @p Tabbed
  583.      *        mode. If empty, the item text is used instead.
  584.      * @param pixmap Used in @p IconList mode. You should prefer a pixmap
  585.      *        with size 32x32 pixels.
  586.      *
  587.      * @return The page widget which must be used as the toplevel widget for
  588.      *         the page.
  589.      */
  590.     QGrid *addGridPage( int n, Orientation dir,
  591.             const QString &itemName,
  592.             const QString &header=QString::null,
  593.             const QPixmap &pixmap=QPixmap() );
  594.  
  595.  
  596.     /**
  597.      * This is like addGridPage() just above, with the difference
  598.      * that the first element is a list of strings.
  599.      *
  600.      * These strings are used to form a path
  601.      * of folders down to the given page. The initial elements are names
  602.      * for the folders, while the last element is the name of the page.
  603.      * Note: This does yet only work for the @p TreeList face. Later this may
  604.      * be added for the @p IconList face too. In other faces than the
  605.      * @p TreeList, all the strings except the last one is ignored.
  606.      **/
  607.     QGrid *addGridPage( int n, Orientation dir,
  608.             const QStringList &items,
  609.             const QString &header=QString::null,
  610.             const QPixmap &pixmap=QPixmap() );
  611.  
  612.  
  613.     /**
  614.      * Sets the icon used in @p TreeList Mode for the given path.
  615.      *
  616.      * @param path The path for which this icon should be shown.
  617.      * @param pixmap The icon used.
  618.      **/
  619.     void setFolderIcon(const QStringList &path,const QPixmap &pixmap);
  620.  
  621.     /**
  622.      * Make a main widget.
  623.      *
  624.      * The function will make a QFrame widget
  625.      * and use setMainWidget() to register it. You can @em not use this
  626.      * function more than once, @em not if you have already defined a
  627.      * main widget with setMainWidget() and @em not if you have used the
  628.      * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed,
  629.      * @p TreeList).
  630.      *
  631.      * @return The main widget or 0 if any of the rules described above
  632.      *         were broken.
  633.      */
  634.     QFrame *makeMainWidget();
  635.  
  636.     /**
  637.      * Make a main widget.
  638.      *
  639.      * The function will make a QVBox widget
  640.      * and use setMainWidget() to register it. You @em can use this
  641.      * function more than once, but @em not if you have already defined a
  642.      * main widget with setMainWidget() and @em not if you have used the
  643.      * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed,
  644.      * @p TreeList, @p IconList).
  645.      *
  646.      * @return The main widget or 0 if any of the rules described above
  647.      *         were broken.
  648.      */
  649.     QVBox *makeVBoxMainWidget();
  650.  
  651.     /**
  652.      * Make a main widget.
  653.      *
  654.      * The function will make a QHBox widget
  655.      * and use setMainWidget() to register it. You can @em not use this
  656.      * function more than once, @em not if you have already defined a
  657.      * main widget with setMainWidget() and @p not if you have used the
  658.      * constructor where you define the face (@p Plain, @p Swallow, @p Tabbed,
  659.      * @p TreeList, @p IconList).
  660.      *
  661.      * @return The main widget or 0 if any of the rules described above
  662.      *         were broken.
  663.      */
  664.     QHBox *makeHBoxMainWidget();
  665.  
  666.     /**
  667.      * Make a main widget.
  668.      *
  669.      * The function will make a QGrid widget
  670.      * and use setMainWidget() to register it. You can @em not use this
  671.      * function more than once, @em not if you have already defined a
  672.      * main widget with setMainWidget and @em not if you have used the
  673.      * constructor where you define the face (Plain, Swallow, Tabbed,
  674.      * TreeList, IconList).
  675.      *
  676.      * @param n Specifies the number of columns if 'dir' is Qt::Horizontal
  677.      *          or the number of rows if 'dir' is Qt::Vertical.
  678.      * @param dir Can be Qt::Horizontal or Qt::Vertical.
  679.      *
  680.      * @return The main widget or 0 if any of the rules described above
  681.      *         were broken.
  682.      */
  683.     QGrid *makeGridMainWidget( int n, Orientation dir );
  684.  
  685.  
  686.     /**
  687.      * Hide or display the a separator line drawn between the action
  688.      * buttons an the main widget.
  689.      */
  690.     void enableButtonSeparator( bool state );
  691.  
  692.     /**
  693.      * Hide or display a general action button.
  694.      *
  695.      *  Only buttons that have
  696.      * been created in the constructor can be displayed. This method will
  697.      * not create a new button.
  698.      *
  699.      * @param id Button identifier.
  700.      * @param state true display the button(s).
  701.      */
  702.     void showButton( ButtonCode id, bool state );
  703.  
  704.     /**
  705.      * Hide or display the OK button.
  706.      *
  707.      *  The OK button must have
  708.      * been created in the constructor to be displayed.
  709.      *
  710.      * @param state If @p true, display the button(s).
  711.      */
  712.     void showButtonOK( bool state );
  713.  
  714.     /**
  715.      * Hide or display the Apply button.
  716.      *
  717.      *  The Apply button must have
  718.      * been created in the constructor to be displayed.
  719.      *
  720.      * @param state true display the button(s).
  721.      */
  722.     void showButtonApply( bool state );
  723.  
  724.     /**
  725.      * Hide or display the Cancel button. The Cancel button must have
  726.      * been created in the constructor to be displayed.
  727.      *
  728.      * @param state @p true display the button(s).
  729.      */
  730.     void showButtonCancel( bool state );
  731.  
  732.     /**
  733.      * Sets the page with @p index to be displayed.
  734.      *
  735.      * This method will only
  736.      * work when the dialog is using the predefined shape of TreeList,
  737.      * IconList or Tabbed.
  738.      *
  739.      * @param index Index of the page to be shown.
  740.      * @return @p true if the page is shown, @p false otherwise.
  741.      */
  742.     bool showPage( int index );
  743.  
  744.     /**
  745.      * Returns the index of the active page.
  746.      *
  747.      * This method will only work when the dialog is using the
  748.      * predefined shape of Tabbed, TreeList or IconList.
  749.      *
  750.      * @return The page index or -1 if there is no active page.
  751.      */
  752.     int activePageIndex() const;
  753.  
  754.  
  755.     /**
  756.      * Returns the index of a page created with addPage(),
  757.      * addVBoxPage(), addHBoxPage() or addGridPage().
  758.      * You can can compare this index with the value returned from
  759.      * activePageIndex() if you need to do some page specific actions
  760.      * in your code.
  761.      *
  762.      * The returned index will never change so you can safely use this
  763.      * function once and save the value.
  764.      *
  765.      * @param widget The widget returned by addPage(), addVBoxPage(),
  766.      * addHBoxPage() or addGridPage().
  767.      *
  768.      * @return The index or -1 if the face is not Tabbed, TreeList or
  769.      *         IconList
  770.      */
  771.     int pageIndex( QWidget *widget ) const;
  772.  
  773.  
  774.     /**
  775.      * Sets the main user definable widget.
  776.      *
  777.      * If the dialog is using the predefined Swallow mode, the widget will
  778.      * be reparented to the internal swallow control widget. If the dialog
  779.      * is being used in the standard mode then the @p widget must have the
  780.      * dialog as parent.
  781.      *
  782.      * @param widget The widget to be displayed as main widget. If it
  783.      * is 0, then the dialog will show an empty space of 100x100 pixels
  784.      * instead.
  785.      */
  786.     void setMainWidget( QWidget *widget );
  787.  
  788.     /**
  789.      * Returns the main widget if any.
  790.      *
  791.      * @return The current main widget. Can be 0 if no widget has been defined.
  792.      */
  793.     QWidget *mainWidget();
  794.  
  795.     /**
  796.      * Convenience method.
  797.      *
  798.      *  Freezes the dialog size using the minimum size
  799.      * of the dialog. This method should only be called right before
  800.      * show() or exec().
  801.      */
  802.     void disableResize();
  803.  
  804.     /**
  805.      * Convenience method. Sets the initial dialog size.
  806.      *
  807.      *  This method should
  808.      * only be called right before show() or exec(). The initial
  809.      * size will be
  810.      * ignored if smaller than the dialog's minimum size.
  811.      *
  812.      * @param s Startup size.
  813.      * @param noResize If @p true the dialog cannot be resized.
  814.      */
  815.     void setInitialSize( const QSize &s, bool noResize=false );
  816.  
  817.     /**
  818.      * Convenience method. Add a size to the default minimum size of a
  819.      * dialog.
  820.      *
  821.      * This method should only be called right before show() or
  822.      * exec().
  823.      *
  824.      * @param s  Size added to minimum size.
  825.      * @param noResize If @p true the dialog cannot be resized.
  826.      */
  827.     void incInitialSize( const QSize &s, bool noResize=false );
  828.  
  829.    /**
  830.     * read the dialogs size from the configuration according to the screen size.
  831.     * If no size is saved for one dimension of the screen, sizeHint() is returned.
  832.     *
  833.     * @param groupName Name of the group to read from. The old group
  834.     *                  of KGlobal::config is preserved.
  835.     */
  836.    QSize configDialogSize( const QString& groupName ) const;
  837.  
  838.    /**
  839.     * read the dialogs size from the configuration according to the screen size.
  840.     * If no size is saved for one dimension of the screen, sizeHint() is returned.
  841.     *
  842.     * @param config The KConfig object to read from
  843.     * @param groupName Name of the group to read from. The old group
  844.     *                  of KGlobal::config is preserved.
  845.     * @since 3.2
  846.     */
  847.    QSize configDialogSize( KConfig& config, const QString& groupName ) const;
  848.  
  849.    /**
  850.     * save the dialogs size dependant on the screen dimension either to the
  851.     * global or application config file.
  852.     *
  853.     * @param groupName The group to which the dialogs size is saved. See configDialogSize
  854.     * to read the size.
  855.     * @param global Set to true if the entry should go to the global config rather
  856.     *        than to the applications config. Default is false.
  857.     */
  858.    void saveDialogSize( const QString& groupName, bool global=false );
  859.  
  860.    /**
  861.     * save the dialogs size dependant on the screen dimension.
  862.     *
  863.     * @param config The KConfig object to write to.
  864.     * @param groupName The group to which the dialogs size is saved. See
  865.     * configDialogSize to read the size.
  866.     * @param global Set to true if the entry should go to the global config.
  867.     *        Default is false.
  868.     * @since 3.2
  869.     */
  870.    void saveDialogSize( KConfig& config, const QString& groupName,
  871.                  bool global=false ) const;
  872.  
  873.     /**
  874.      * Sets the appearance of the OK button.
  875.      *
  876.      * If the default parameters are used
  877.      * (that is, if no KGuiItem is given) KStdGuiItem::ok() is used.
  878.      *
  879.      * @param item KGuiItem.
  880.      * @since 3.2
  881.      */
  882.     void setButtonOK( const KGuiItem &item = KStdGuiItem::ok() );
  883.  
  884.     /**
  885.      * @deprecated. Use setButtonOk() instead.
  886.      *
  887.      * Sets the text of the OK button.
  888.      *
  889.      * If the default parameters are used
  890.      * (that is, if no parameters are given) the standard texts are set:
  891.      * The button shows "OK", the tooltip contains "Accept settings."
  892.      * (internationalized) and the quickhelp text explains the standard
  893.      * behavior of the OK button in settings dialogs.
  894.      *
  895.      * @param text Button text.
  896.      * @param tooltip Tooltip text.
  897.      * @param quickhelp Quick help text.
  898.      */
  899.     void setButtonOKText( const QString &text=QString::null,
  900.               const QString &tooltip=QString::null,
  901.               const QString &quickhelp=QString::null ) KDE_DEPRECATED;
  902.  
  903.     /**
  904.      * Sets the appearance of the Apply button.
  905.      *
  906.      * If the default parameters are used
  907.      * (that is, if no KGuiItem is given) KStdGuiItem::apply() is used.
  908.      *
  909.      * @param item KGuiItem.
  910.      * @since 3.2
  911.      */
  912.     void setButtonApply( const KGuiItem &item = KStdGuiItem::apply() );
  913.  
  914.     /**
  915.      * @deprecated. Use setButtonApply() instead.
  916.      *
  917.      * Sets the text of the Apply button.
  918.      *
  919.      * If the default parameters are
  920.      * used (that is, if no parameters are given) the standard texts are set:
  921.      * The button shows "Apply", the tooltip contains "Apply settings."
  922.      * (internationalized) and the quickhelp text explains the standard
  923.      * behavior of the apply button in settings dialogs.
  924.      *
  925.      * @param text Button text.
  926.      * @param tooltip Tooltip text.
  927.      * @param quickhelp Quick help text.
  928.      */
  929.     void setButtonApplyText( const QString &text=QString::null,
  930.                  const QString &tooltip=QString::null,
  931.                  const QString &quickhelp=QString::null ) KDE_DEPRECATED;
  932.  
  933.     /**
  934.      * Sets the appearance of the Cancel button.
  935.      *
  936.      * If the default parameters are used
  937.      * (that is, if no KGuiItem is given) KStdGuiItem::cancel() is used.
  938.      *
  939.      * @param item KGuiItem.
  940.      * @since 3.2
  941.      */
  942.     void setButtonCancel( const KGuiItem &item = KStdGuiItem::cancel() );
  943.  
  944.     /**
  945.      * @deprecated. Use setButtonCancel() instead.
  946.      *
  947.      * Sets the text of the Cancel button.
  948.      *
  949.      *  If the default parameters are
  950.      * used (that is, if no parameters are given) the standard texts are set:
  951.      * The button shows "Cancel", everything else will not be set.
  952.      *
  953.      * @param text Button text.
  954.      * @param tooltip Tooltip text.
  955.      * @param quickhelp Quick help text.
  956.      */
  957.     void setButtonCancelText( const QString &text=QString::null,
  958.                   const QString &tooltip=QString::null,
  959.                   const QString &quickhelp=QString::null ) KDE_DEPRECATED;
  960.  
  961.     /**
  962.      * Sets the text of any button.
  963.      *
  964.      * @param id The button identifier.
  965.      * @param text Button text.
  966.      */
  967.     void setButtonText( ButtonCode id, const QString &text );
  968.  
  969.     /**
  970.      * Sets the tooltip text of any button.
  971.      *
  972.      * @param id The button identifier.
  973.      * @param text Button text.
  974.      */
  975.     void setButtonTip( ButtonCode id, const QString &text );
  976.  
  977.     /**
  978.      * Sets the "What's this?" text of any button.
  979.      *
  980.      * @param id The button identifier.
  981.      * @param text Button text.
  982.      */
  983.     void setButtonWhatsThis( ButtonCode id, const QString &text );
  984.  
  985.     /**
  986.      * Sets the KGuiItem directly for the button instead of using 3 methods to
  987.      * set the text, tooltip and whatsthis strings. This also allows to set an
  988.      * icon for the button which is otherwise not possible for the extra
  989.      * buttons beside Ok, Cancel and Apply.
  990.      *
  991.      * @param id The button identifier.
  992.      * @param item The KGuiItem for the button.
  993.      *
  994.      * @since 3.3
  995.      */
  996.     void setButtonGuiItem( ButtonCode id, const KGuiItem &item );
  997.  
  998.     /**
  999.      * This function has only effect in TreeList mode.
  1000.      *
  1001.      * Defines how the tree list widget is resized when the dialog is
  1002.      * resized horizontally. By default the tree list keeps its width
  1003.      * when the dialog becomes wider.
  1004.      *
  1005.      * @param state The resize mode. If false (default) the tree list keeps
  1006.      *        its current width when the dialog becomes wider.
  1007.      */
  1008.      void setTreeListAutoResize( bool state );
  1009.  
  1010.     /**
  1011.      * This function has only effect in TreeList mode.
  1012.      *
  1013.      * This tells the widgets whether the icons given in the addPage,
  1014.      * addVBoxPage, addHBoxPage, or addGridPage methods should
  1015.      * be shown in the TreeList.
  1016.      *
  1017.      * Note: This method must be called before calling any of the methods
  1018.      * which add icons to the page.
  1019.      *
  1020.      * @param state If true the icons are shown.
  1021.      **/
  1022.     void setShowIconsInTreeList(bool state);
  1023.  
  1024.     /**
  1025.      * This function has only effect in TreeList mode.
  1026.      *
  1027.      * This tells the widgets whether the root should be decorated.
  1028.      * For details see QListView::setRootIsDecorated
  1029.      *
  1030.      * @param state Root will be decorated if true.
  1031.      **/
  1032.     void setRootIsDecorated( bool state );
  1033.  
  1034.     /**
  1035.      * This function has only effect in TreeList mode.
  1036.      *
  1037.      * This tells the TreeList to unfold the whole tree so that all entries
  1038.      * are visible.
  1039.      *
  1040.      * If the list is empty when you call this method newly created entries
  1041.      * will not automatically be opened. If the @p persist flag is set opened
  1042.      * entries cannot be closed again, though.
  1043.      *
  1044.      * @param persist If true the tree always stays unfolded.
  1045.      * @since 3.2
  1046.      */
  1047.     void unfoldTreeList( bool persist = false );
  1048.  
  1049.     /**
  1050.      * Add a widget at the bottom of the TreeList/IconList.
  1051.      *
  1052.      * @param widget  The widget to be added. It will be reparented into the
  1053.      *                KJanusWidget, therefor it will be deleted with the
  1054.      *                KJanusWidget, too. To be on the save side just don't keep
  1055.      *                the pointer to this widget.
  1056.      */
  1057.     void addWidgetBelowList( QWidget * widget );
  1058.  
  1059.     /**
  1060.      * Add a button at the bottom of the TreeList/IconList.
  1061.      *
  1062.      * @param text     The text on the PushButton.
  1063.      * @param recv     The object that is to receive the signal when the button
  1064.      *                 is clicked.
  1065.      * @param slot     The slot to connect to the clicked signal of the button.
  1066.      *
  1067.      * @since 3.2
  1068.      */
  1069.     void addButtonBelowList( const QString & text, QObject * recv, const char * slot );
  1070.  
  1071.     /**
  1072.      * The same as the above function, but with a KGuiItem providing the text
  1073.      * and icon for the button at the bottom of the TreeList/IconList.
  1074.      *
  1075.      * @param guiitem  The text and icon on the PushButton.
  1076.      * @param recv     The object that is to receive the signal when the button
  1077.      *                 is clicked.
  1078.      * @param slot     The slot to connect to the clicked signal of the button.
  1079.      *
  1080.      * @since 3.2
  1081.      */
  1082.     void addButtonBelowList( const KGuiItem & guiitem, QObject * recv, const char * slot );
  1083.  
  1084.     /**
  1085.      * This function has only effect in IconList mode.
  1086.      *
  1087.      * Defines how the icon list widget is displayed. By default it is
  1088.      * the widgets in the dialog pages that decide the minimum height
  1089.      * of the dialog. A vertical scrollbar can be used in the icon list
  1090.      * area.
  1091.      *
  1092.      * @param state The visibility mode. If true, the minimum height is
  1093.      *        adjusted so that every icon in the list is visible at the
  1094.      *        same time. The vertical scrollbar will never be visible.
  1095.      */
  1096.     void setIconListAllVisible( bool state );
  1097.  
  1098.     /**
  1099.      * Check whether the background tile is set or not.
  1100.      *
  1101.      * @return @p true if there is defined a background tile.
  1102.      */
  1103.     static bool haveBackgroundTile();
  1104.  
  1105.     /**
  1106.      * Returns a pointer to the background tile if there is one.
  1107.      *
  1108.      * @return The tile pointer or 0 if no tile is defined.
  1109.      *
  1110.      **/
  1111.     static const QPixmap *backgroundTile();
  1112.     /**
  1113.      * @deprecated
  1114.      * Use backgroundTile() instead.
  1115.      */
  1116.     static const QPixmap *getBackgroundTile() KDE_DEPRECATED;
  1117.  
  1118.     /**
  1119.      * Sets the background tile.
  1120.      *
  1121.      *  If it is Null (0), the background image is deleted.
  1122.      *
  1123.      * @param pix The background tile.
  1124.      */
  1125.     static void setBackgroundTile( const QPixmap *pix );
  1126.  
  1127.     /**
  1128.      * Enable hiding of the background tile (if any).
  1129.      *
  1130.      * @param state @p true will make the tile visible.
  1131.      */
  1132.     void showTile( bool state );
  1133.  
  1134.     /**
  1135.      * @deprecated
  1136.      * Do not use this method. It is included for compatibility reasons.
  1137.      *
  1138.      * This method returns the border widths in all directions the dialog
  1139.      * needs for itself. Respect this, or get bad looking results.
  1140.      * The references are upper left x (@p ulx), upper left y (@p uly),
  1141.      * lower right x (@p lrx), and lower left y (@p lly).
  1142.      * The results are differences in pixels from the
  1143.      * dialogs corners.
  1144.      */
  1145.     void  getBorderWidths( int& ulx, int& uly, int& lrx, int& lry ) const KDE_DEPRECATED;
  1146.  
  1147.     /**
  1148.      * @deprecated
  1149.      * Do not use this method. It is included for compatibility reasons.
  1150.      *
  1151.      * This method returns the contents rectangle of the work area. Place
  1152.      * your widgets inside this rectangle, and use it to set up
  1153.      * their geometry. Be careful: The rectangle is only valid after
  1154.      * resizing the dialog, as it is a result of the resizing process.
  1155.      * If you need the "overhead" the dialog needs for its elements,
  1156.      * use getBorderWidths().
  1157.      */
  1158.     QRect getContentsRect() const KDE_DEPRECATED;
  1159.  
  1160.     /**
  1161.      * Calculate the size hint for the dialog.
  1162.      *
  1163.      * With this method it is easy to calculate a size hint for a
  1164.      * dialog derived from KDialogBase if you know the width and height of
  1165.      * the elements you add to the widget. The rectangle returned is
  1166.      * calculated so that all elements exactly fit into it. Thus, you may
  1167.      * set it as a minimum size for the resulting dialog.
  1168.      *
  1169.      * You should not need to use this method and never if you use one of
  1170.      * the predefined shapes.
  1171.      *
  1172.      * @param w The width of you special widget.
  1173.      * @param h The height of you special widget.
  1174.      * @return The minimum width and height of the dialog using @p w and @p h
  1175.      * as the size of the main widget.
  1176.      */
  1177.     QSize calculateSize( int w, int h ) const;
  1178.  
  1179.     /**
  1180.      * Returns the help link text.
  1181.      *
  1182.      *  If no text has been defined,
  1183.      * "Get help..." (internationalized) is returned.
  1184.      *
  1185.      * @return The help link text.
  1186.      */
  1187.     QString helpLinkText() const;
  1188.  
  1189.     /**
  1190.      * Returns the action button that corresponds to the @p id.
  1191.      *
  1192.      * Normally
  1193.      * you should not use this function. @em Never delete the object returned
  1194.      * by this function. See also enableButton(), showButton(),
  1195.      * setButtonTip(), setButtonWhatsThis(), and setButtonText().
  1196.      *
  1197.      * @param id Integer identifier of the button.
  1198.      * @return The action button or 0 if the button does not exists.
  1199.      *
  1200.      * FIXME KDE 4: Return the actual KPushButton instead of QPushButton (Martijn)
  1201.      */
  1202.     QPushButton *actionButton( ButtonCode id );
  1203.  
  1204.   public slots:
  1205.     /**
  1206.      * Enable or disable (gray out) a general action button.
  1207.      *
  1208.      * @param id Button identifier.
  1209.      * @param state @p true enables the button(s).
  1210.      */
  1211.     void enableButton( ButtonCode id, bool state );
  1212.  
  1213.     /**
  1214.      * Enable or disable (gray out) the OK button.
  1215.      *
  1216.      * @param state @p true enables the button.
  1217.      */
  1218.     void enableButtonOK( bool state );
  1219.  
  1220.     /**
  1221.      * Enable or disable (gray out) the Apply button.
  1222.      *
  1223.      * @param state true enables the button.
  1224.      */
  1225.     void enableButtonApply( bool state );
  1226.  
  1227.     /**
  1228.      * Enable or disable (gray out) the Cancel button.
  1229.      *
  1230.      * @param state true enables the button.
  1231.      */
  1232.     void enableButtonCancel( bool state );
  1233.  
  1234.     /**
  1235.      * Display or hide the help link area on the top of the dialog.
  1236.      *
  1237.      * @param state @p true will display the area.
  1238.      */
  1239.     void enableLinkedHelp( bool state );
  1240.  
  1241.     /**
  1242.      * Destruct the Dialog delayed.
  1243.      *
  1244.      * You can call this function from
  1245.      * slots like closeClicked() and hidden().
  1246.      * You should not use the dialog any more after
  1247.      * calling this function.
  1248.      * @since 3.1
  1249.      */
  1250.     void delayedDestruct();
  1251.  
  1252.     /**
  1253.      * Sets the text that is shown as the linked text.
  1254.      *
  1255.      * If text is empty,
  1256.      * the text "Get help..." (internationalized) is used instead.
  1257.      *
  1258.      * @param text The link text.
  1259.      */
  1260.     void setHelpLinkText( const QString &text );
  1261.  
  1262.     /**
  1263.      * Sets the help path and topic.
  1264.      *
  1265.      * @param anchor Defined anchor in your docbook sources
  1266.      * @param appname Defines the appname the help belongs to
  1267.      *                If empty it's the current one
  1268.      *
  1269.      * @note The help button works differently for the class
  1270.      * KCMultiDialog, so it does not make sense to call this
  1271.      * function for Dialogs of that type.  See
  1272.      * KCMultiDialog::slotHelp() for more information.
  1273.      */
  1274.     void setHelp( const QString &anchor,
  1275.           const QString &appname = QString::null );
  1276.  
  1277.     /**
  1278.      * Connected to help link label.
  1279.      */
  1280.     void helpClickedSlot( const QString & );
  1281.  
  1282.     /**
  1283.      * Sets the status of the Details button.
  1284.      */
  1285.     void setDetails(bool showDetails);
  1286.  
  1287.     /**
  1288.      * Sets the widget that gets shown when "Details" is enabled.
  1289.      *
  1290.      * The dialog takes over ownership of the widget.
  1291.      * Any previously set widget gets deleted.
  1292.      */
  1293.     void setDetailsWidget(QWidget *detailsWidget);
  1294.  
  1295.     /**
  1296.      * This method is called automatically whenever the background has
  1297.      * changed. You do not need to use this method.
  1298.      */
  1299.     void updateBackground();
  1300.  
  1301.     /**
  1302.      * Force closing the dialog, setting its result code to the one Esc would set.
  1303.      * You shouldn't use this, generally (let the user make his choice!)
  1304.      * but it can be useful when you need to make a choice after a timeout
  1305.      * has happened, or when the parent widget has to go somewhere else
  1306.      * (e.g. html redirections).
  1307.      * @since 3.1
  1308.      */
  1309.     void cancel();
  1310.  
  1311.   signals:
  1312.     /**
  1313.      * The Help button was pressed. This signal is only emitted if
  1314.      * slotHelp() is not replaced.
  1315.      */
  1316.     void helpClicked();
  1317.  
  1318.     /**
  1319.      * The Default button was pressed. This signal is only emitted if
  1320.      * slotDefault() is not replaced.
  1321.      */
  1322.     void defaultClicked();
  1323.  
  1324.  
  1325.     /**
  1326.      * The User3 button was pressed. This signal is only emitted if
  1327.      * slotUser3() is not replaced.
  1328.      */
  1329.     void user3Clicked();
  1330.  
  1331.     /**
  1332.      * The User2 button was pressed. This signal is only emitted if
  1333.      * slotUser2() is not replaced.
  1334.      */
  1335.     void user2Clicked();
  1336.  
  1337.     /**
  1338.      * The User1 button was pressed. This signal is only emitted if
  1339.      * slotUser1() is not replaced.
  1340.      */
  1341.     void user1Clicked();
  1342.  
  1343.     /**
  1344.      * The Apply button was pressed. This signal is only emitted if
  1345.      * slotApply() is not replaced.
  1346.      */
  1347.     void applyClicked();
  1348.  
  1349.     /**
  1350.      * The Try button was pressed. This signal is only emitted if
  1351.      * slotTry() is not replaced.
  1352.      */
  1353.     void tryClicked();
  1354.  
  1355.     /**
  1356.      * The OK button was pressed. This signal is only emitted if
  1357.      * slotOk() is not replaced.
  1358.      */
  1359.     void okClicked();
  1360.  
  1361.     /**
  1362.      * The Yes button was pressed. This signal is only emitted if
  1363.      * slotYes() is not replaced.
  1364.      */
  1365.     void yesClicked();
  1366.  
  1367.     /**
  1368.      * The No button was pressed. This signal is only emitted if
  1369.      * slotNo() is not replaced.
  1370.      */
  1371.     void noClicked();
  1372.  
  1373.     /**
  1374.      * The Cancel button was pressed. This signal is only emitted if
  1375.      * slotCancel() is not replaced.
  1376.      */
  1377.     void cancelClicked();
  1378.  
  1379.     /**
  1380.      * The Close button was pressed. This signal is only emitted if
  1381.      * slotClose() is not replaced.
  1382.      */
  1383.     void closeClicked();
  1384.  
  1385.     /**
  1386.      * Do not use this signal. Is is kept for compatibility reasons.
  1387.      * @deprecated Use applyClicked() instead.
  1388.      */
  1389.     void apply();
  1390.  
  1391.     /**
  1392.      * The background tile has changed.
  1393.      */
  1394.     void backgroundChanged();
  1395.  
  1396.     /**
  1397.      * The dialog is about to be hidden.
  1398.      *
  1399.      * A dialog is hidden after a user clicks a button that ends
  1400.      * the dialog or when the user switches to another desktop or
  1401.      * minimizes the dialog.
  1402.      */
  1403.     void hidden();
  1404.  
  1405.     /**
  1406.      * The dialog has finished.
  1407.      *
  1408.      * A dialog emits finished after a user clicks a button that ends
  1409.      * the dialog.
  1410.      *
  1411.      * This signal is also emitted when you call hide()
  1412.      *
  1413.      * If you have stored a pointer to the
  1414.      * dialog do @em not try to delete the pointer in the slot that is
  1415.      * connected to this signal.
  1416.      *
  1417.      * You should use delayedDestruct() instead.
  1418.      */
  1419.     void finished();
  1420.  
  1421.     /**
  1422.      * The detailsWidget is about to get shown. This is your last chance
  1423.      * to call setDetailsWidget if you haven't done so yet.
  1424.      */
  1425.     void aboutToShowDetails();
  1426.  
  1427.     /**
  1428.      * A page is about to be shown. This signal is only emitted for the TreeList
  1429.      * and IconList faces.
  1430.      */
  1431.     void aboutToShowPage(QWidget *page);
  1432.  
  1433.   protected:
  1434.     /**
  1435.      * Maps some keys to the actions buttons. F1 is mapped to the Help
  1436.      * button if present and Escape to the Cancel or Close if present. The
  1437.      * button action event is animated.
  1438.      */
  1439.     virtual void keyPressEvent( QKeyEvent *e );
  1440.  
  1441.     /**
  1442.      * Emits the #hidden signal. You can connect to that signal to
  1443.      * detect when a dialog has been closed.
  1444.      */
  1445.     virtual void hideEvent( QHideEvent * );
  1446.  
  1447.     /**
  1448.      * Detects when a dialog is being closed from the window manager
  1449.      * controls. If the Cancel or Close button is present then the button
  1450.      * is activated. Otherwise standard QDialog behavior
  1451.      * will take place.
  1452.      */
  1453.     virtual void closeEvent( QCloseEvent *e );
  1454.  
  1455.   protected slots:
  1456.     /**
  1457.      * Activated when the Help button has been clicked. If a help
  1458.      * text has been defined, the help system will be activated.
  1459.      */
  1460.     virtual void slotHelp();
  1461.  
  1462.     /**
  1463.      * Activated when the Default button has been clicked.
  1464.      */
  1465.     virtual void slotDefault();
  1466.  
  1467.     /**
  1468.      * Activated when the Details button has been clicked.
  1469.      * @see detailsClicked(bool)
  1470.      */
  1471.     virtual void slotDetails();
  1472.  
  1473.     /**
  1474.      * Activated when the User3 button has been clicked.
  1475.      */
  1476.     virtual void slotUser3();
  1477.  
  1478.     /**
  1479.      * Activated when the User2 button has been clicked.
  1480.      */
  1481.     virtual void slotUser2();
  1482.  
  1483.     /**
  1484.      * Activated when the User1 button has been clicked.
  1485.      */
  1486.     virtual void slotUser1();
  1487.  
  1488.     /**
  1489.      * Activated when the Ok button has been clicked. The
  1490.      * QDialog::accept() is activated.
  1491.      */
  1492.     virtual void slotOk();
  1493.  
  1494.     /**
  1495.      * Activated when the Apply button has been clicked.
  1496.      */
  1497.     virtual void slotApply();
  1498.  
  1499.     /**
  1500.      * Activated when the Try button has been clicked.
  1501.      */
  1502.     virtual void slotTry();
  1503.  
  1504.     /**
  1505.      * Activated when the Yes button has been clicked. The
  1506.      * QDialog::done( Yes ) is activated.
  1507.      */
  1508.     virtual void slotYes();
  1509.  
  1510.     /**
  1511.      * Activated when the Yes button has been clicked. The
  1512.      * QDialog::done( No ) is activated.
  1513.      */
  1514.     virtual void slotNo();
  1515.  
  1516.     /**
  1517.      * Activated when the Cancel button has been clicked. The
  1518.      * QDialog::reject() is activated in regular mode and
  1519.      * QDialog::done( Cancel ) when in message box mode.
  1520.      */
  1521.     virtual void slotCancel();
  1522.  
  1523.     /**
  1524.      * Activated when the Close button has been clicked. The
  1525.      * QDialog::reject() is activated.
  1526.      */
  1527.     virtual void slotClose();
  1528.  
  1529.     /**
  1530.      * @deprecated
  1531.      * Do not use this slot. Is is kept for compatibility reasons.
  1532.      * Activated when the Apply button has been clicked
  1533.      */
  1534.     virtual void applyPressed();
  1535.  
  1536.     /**
  1537.      * Updates the margins and spacings.
  1538.      */
  1539.     void updateGeometry();
  1540.  
  1541.     /**
  1542.      * Deletes the dialog immediately. If you want to delete the dialog
  1543.      * delayed use delayedDestruct() or QObject::deleteLater().
  1544.      *
  1545.      * Attention: Do no use connect this slot to signals from user
  1546.      * actions!
  1547.      */
  1548.     void slotDelayedDestruct();
  1549.  
  1550.   private:
  1551.     /**
  1552.      * Prepares the layout that manages the widgets of the dialog
  1553.      */
  1554.     void setupLayout();
  1555.  
  1556.     /**
  1557.      * Prepares a relay that is used to send signals between
  1558.      * all KDialogBase instances of a program. Should only be used in the
  1559.      * constructor.
  1560.      */
  1561.     void makeRelay();
  1562.  
  1563.     /**
  1564.      * Makes the button box and all the buttons in it. This method must
  1565.      * only be ran once from the constructor.
  1566.      *
  1567.      * @param buttonMask Specifies what buttons will be made.
  1568.      * @param defaultButton Specifies which button will be marked as
  1569.      *        the default. Use ButtonCode::NoDefault to indicate that no button
  1570.      *        should be marked as the default button.
  1571.      * @param user1 User button1 item.
  1572.      * @param user2 User button2 item.
  1573.      * @param user2 User button3 item.
  1574.      */
  1575.     void makeButtonBox( int mask, ButtonCode defaultButton,
  1576.             const KGuiItem &user1 = KGuiItem(),
  1577.             const KGuiItem &user2 = KGuiItem(),
  1578.             const KGuiItem &user3 = KGuiItem() );
  1579.  
  1580.     /**
  1581.      * Sets the action button that is marked as default and has focus.
  1582.      *
  1583.      * @param p The action button.
  1584.      * @param isDefault If true, make the button default
  1585.      * @param isFocus If true, give the button focus.
  1586.      */
  1587.     void setButtonFocus( QPushButton *p, bool isDefault, bool isFocus );
  1588.  
  1589.     /**
  1590.      * Prints an error message using qDebug if makeMainWidget ,
  1591.      * makeVBoxMainWidget , makeHBoxMainWidget or
  1592.      * makeGridMainWidget failed.
  1593.      */
  1594.     void printMakeMainWidgetError();
  1595.  
  1596.   private slots:
  1597.     /**
  1598.      * Sets the action button order according to the 'style'.
  1599.      *
  1600.      * @param style The style index.
  1601.      */
  1602.     void setButtonStyle( int style );
  1603.  
  1604.  
  1605.   private:
  1606.     QBoxLayout   *mTopLayout;
  1607.     QWidget      *mMainWidget;
  1608.     KURLLabel    *mUrlHelp;
  1609.     KJanusWidget *mJanus;
  1610.     KSeparator   *mActionSep;
  1611.  
  1612.     bool mIsActivated;
  1613.  
  1614.     QString mAnchor;
  1615.     QString mHelpApp;
  1616.     QString mHelpLinkText;
  1617.  
  1618.     static KDialogBaseTile *mTile;
  1619.     bool   mShowTile;
  1620.  
  1621.     bool mMessageBoxMode;
  1622.     int  mButtonOrientation;
  1623.     ButtonCode mEscapeButton;
  1624.  
  1625.   protected:
  1626.     virtual void virtual_hook( int id, void* data );
  1627.   private:
  1628.     class KDialogBasePrivate;
  1629.     KDialogBasePrivate* const d;
  1630. };
  1631.  
  1632. #endif
  1633.